/**
 * Copyright 2010, Lars J. Nilsson <http://www.larsan.net> 
 * 
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU Lesser General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public License
 * along with this program.  If not, see <http://www.gnu.org/licenses/>.
 */

package net.larsan.dconf;

import java.util.List;

/**
 * This is the main store of nodes and attributes. It acts as 
 * a proxy between the nodes and the underlying storage mechanism. 
 * 
 * @author Lars J. Nilsson
 */
public interface DNodeStore {
	
	/**
	 * Get a node from the store, and optionally create it. If the
	 * node does not exist, and 'create' is false, this method returns
	 * null.
	 * 
	 * @param path Path to get, must not be null
	 * @param create True to create node if it does not exist, false otherwise
	 * @return A node, or null if not created or found
	 */
	public DNode get(DPath path, boolean create);
	
	/**
	 * Get a node from the store. If the
	 * node does not exist this method returns null.
	 * 
	 * @param path Path to get, must not be null
	 * @return A node, or null if not found
	 */
	public DNode get(DPath path);
	
	/**
	 * The root domain is the default, mandatory domain. This method
	 * returns the root node for the root domain.
	 * 
	 * @return The root domain node, never null
	 */
	public DNode getRootDomainNode();
	
	
	/**
	 * Get all domain nodes, excluding the root domain. The order of
	 * the domain is not significant.
	 * 
	 * @return A list of domain root nodes, excluding the root domain, never null
	 */
	public List<DNode> getDomainNodes();
	
	
	/**
	 * Get a single attribute. This method returns null if
	 * the attribute cannot be found, or the node cannot be 
	 * found.
	 * 
	 * @param path Node path to get attribute from, must not be null
	 * @param attribute Attribute name to get, must not be null
	 * @return The attribute value if found, null otherwise
	 */
	public String get(DPath path, String attribute);
	
	
	/**
	 * Set an attribute value and return the old value. The 
	 * denoted node must exist when this method is called, if
	 * it does not a "no such node" exception is found.
	 * 
	 * @param path Node path to set attribute on, must not be null
	 * @param attribute Attribute name to set, must not be null
	 * @param value Attribute value to set, must not be null
	 * @return The old attribute value if found, null otherwise
	 * @throws NoSuchDNodeException If the node does not exist
	 */
	public String set(DPath path, String attribute, String value) throws NoSuchDNodeException;
	
	
	/**
	 * Remove an attribute. THis method fails silently if the
	 * node does not exist, and returns the old value if it, and
	 * the attribute, does.
	 * 
	 * @param path Node path to remove attribute from, must not be null
	 * @param attribute Name of attribute to remove, never null
	 * @return The old attribute value if found, null otherwise
	 */
	public String remove(DPath path, String attribute);
	
	
	/**
	 * Remove a node from the store. This method fails silently if the node
	 * is not found. 
	 * 
	 * @param path Path of node to remove, must not be null
	 */
	public void destroy(DPath path);

	
	/**
	 * @param path Path of node to look for, must not be null
	 * @return True if the node exists, false otherwise
	 */
	public boolean exists(DPath path);
	
}
